<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<html><head><title>Programming in Lua : 15.3</title>
<link rel="stylesheet" type="text/css" href="pil.css">
</head>
<body>
<p class="warning">
<A HREF="contents.html"><IMG TITLE="Programming in Lua (first edition)" SRC="capa.jpg" ALT="" ALIGN="left"></A>This first edition was written for Lua 5.0. While still largely relevant for later versions, there are some differences.<BR>The third edition targets Lua 5.2 and is available at <A HREF="http://www.amazon.com/exec/obidos/ASIN/859037985X/theprogrammil3-20">Amazon</A> and other bookstores.<BR>By buying the book, you also help to <A HREF="../donations.html">support the Lua project</A>.
</p>
<table width="100%" class="nav">
<tr>
<td width="10%" align="left"><a href="15.2.html"><img border="0" src="left.png" alt="Previous"></a></td>
<td width="80%" align="center"><a href="contents.html"><font face="Helvetica,Arial,sanserif">
<font color="gray">Programming in </font><font color="blue"> Lua</font>
</font></a></td>
<td width="10%" align="right"><a href="15.4.html"><img border="0" src="right.png" alt="Next"></a></td>
</tr>
<tr>
<td width="10%" align="left"></td>
<td width="80%" align="center"><a href="contents.html#P2">Part II. Tables and Objects</a>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
<a href="contents.html#15">Chapter 15. Packages</a></td>
<td width="10%" align="right"></td></tr>
</table>
<hr/>
<p><h2>15.3 &ndash; Packages and Files</h2>

<p>Typically, when we write a package,
we put all its code in a single file.
Then, to open or import a package
(that is, to make it available) we just execute that file.
For instance, if we have a file <code>complex.lua</code> with the
definition of our complex package,
the command <code>require "complex"</code> will open the package.
Remember that <code>require</code> avoids loading the same package multiple times.

<p>A recurring issue is the relationship between the
file name and the package name.
Of course, it is a good idea to relate them,
because <code>require</code> works with files,
not with packages.
One solution is to name the file after the package,
followed by some known extension.
Lua does not fix any extension;
it is up to your path to do that.
For instance, if your path includes a component like
<code>"/usr/local/lualibs/?.lua"</code>,
than the package <code>complex</code> may live in a <code>complex.lua</code> file.

<p>Some people prefer the reverse,
to name the package after the file name, dynamically.
That is, if you rename the file, the package is renamed, too.
This solution gives you more flexibility.
For instance, if you get two different packages with the same name,
you do not have to change any of them,
just rename one file.
To implement this naming scheme in Lua,
we use the <code>_REQUIREDNAME</code> variable.
Remember that, when <code>require</code> loads a file,
it defines that variable with the virtual file name.
So, you can write something like the following in your
package:
<pre>
    local P = {}   -- package
    if _REQUIREDNAME == nil then
      complex = P
    else
      _G[_REQUIREDNAME] = P
    end
</pre>
The test allows us to use the package without <code>require</code>.
If <code>_REQUIREDNAME</code> is not defined,
we use a fixed name for the package
(<code>complex</code>, in the example).
Otherwise, the package registers itself with the virtual file name,
whatever it is.
If a user puts the library in file <code>cpx.lua</code>
and runs <code>require"cpx"</code>,
the package loads itself in table <code>cpx</code>.
If another user moves the library to file <code>cpx_v1.lua</code>
and runs <code>require"cpx_v1"</code>,
the package loads itself in table <code>cpx_v1</code>.

<hr/>
<table width="100%" class="nav">
<tr valign="top">
<td width="90%" align="left">
<small>
  Copyright &copy; 2003&ndash;2004 Roberto Ierusalimschy.  All rights reserved.
</small>
</td>
<td width="10%" align="right"><a href="15.4.html"><img border="0" src="right.png" alt="Next"></a></td>
</tr>
</table>


</body></html>

